…7941)

## Explanation

Syncs `PerpsController` from Mobile into Core as
`@metamask/perps-controller` for npm publishing.

**Architecture (latest):** Cross-controller communication uses the
standard `@metamask/messenger` pattern — `messenger.call()` and
`messenger.subscribe()`. Typed `PerpsControllerAllowedActions` /
`PerpsControllerAllowedEvents` define the contract. The only DI
remaining is `PerpsPlatformDependencies.rewards` (RewardsController is
not yet in Core) and platform-specific adapters (logger, metrics,
tracer, stream manager, etc.).

This addresses Mark Stacey's concern from the ADR-42 review:
PerpsController uses the same messenger architecture as all other Core
controllers, with no special DI bridging for controller-to-controller
calls.

**Messenger actions used:**

| Action | Controller |
|--------|-----------|
| `AccountTreeController:getAccountsFromSelectedAccountGroup` |
AccountTreeController |
| `KeyringController:getState` | KeyringController |
| `KeyringController:signTypedMessage` | KeyringController |
| `NetworkController:getState` | NetworkController |
| `NetworkController:getNetworkClientById` | NetworkController |
| `NetworkController:findNetworkClientIdByChainId` | NetworkController |
| `TransactionController:addTransaction` | TransactionController |
| `AuthenticationController:getBearerToken` | AuthenticationController |
| `RemoteFeatureFlagController:getState` | RemoteFeatureFlagController |

**Messenger events subscribed:**
- `RemoteFeatureFlagController:stateChange`
- `AccountTreeController:selectedAccountGroupChange`

**Approach:** Mobile remains the source of truth. A sync script
(`validate-core-sync.sh`) copies controller source to this package,
verifies build + lint, and writes a `.sync-state.json` with commit
hashes and source checksum for conflict detection. This is a
transitional mechanism that goes away when Mobile folds into Core as
`apps/mobile`.

**Key components:**
- `PerpsController` — main controller with state management, messenger
integration, and multi-provider orchestration
- `HyperLiquidProvider` / `MYXProvider` — DEX-specific provider
implementations
- `AggregatedPerpsProvider` — multi-provider aggregation layer
- `ProviderRouter` — routes operations to the appropriate provider
- `SubscriptionMultiplexer` — real-time WebSocket data aggregation
- 13 services: Trading, MarketData, Account, Deposit, Eligibility,
FeatureFlagConfiguration, HyperLiquidClient, HyperLiquidSubscription,
HyperLiquidWallet, MYXClient, DataLake, RewardsIntegration,
TradingReadinessCache
- `PerpsPlatformDependencies` — platform-agnostic injection interface
(rewards, logger, metrics, tracer, stream manager, feature flags, market
data formatters, cache invalidator)

**CI / Testing:** A minimal placeholder test
(`tests/placeholder.test.ts`) is included to satisfy Core's CI
requirement. Full unit tests remain in Mobile (27 suites, 1295 tests
passing) and will be migrated when development moves fully to Core.

## References

- Builds on #7654 (initial `perps-controller` package scaffolding)
- Supersedes #7749 (closed — first full migration attempt)
- Related: #7841 (draft — preview publishing test)
- Mobile messenger migration:
[metamask-mobile@feat/perps/di-refactor-remove-controller-deps](https://github.com/MetaMask/metamask-mobile/tree/feat/perps/di-refactor-remove-controller-deps)
- Mobile preparation:
[metamask-mobile#26064](MetaMask/metamask-mobile#26064)
(ESLint alignment + `validate-core-sync.sh`)
- Mobile isolation:
[metamask-mobile#25813](MetaMask/metamask-mobile#25813)
(isolated perps code, converted imports)
- Architecture position: [PerpsController Location — Position v2
(Post-DI)](https://consensyssoftware.atlassian.net/wiki/spaces/PRDC/pages/400956981249/PerpsController+package+Location+Position+v2+Post-DI)

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- Placeholder test included for CI. Full unit tests remain in Mobile and
will be migrated when development moves fully to Core.
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them
- No breaking changes — messenger migration is internal; existing public
API is preserved

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> Large change that introduces/rewires perps trading flows, WebSocket
subscriptions, feature-flagged provider switching, and transaction
submission via `TransactionController`, increasing risk of runtime, data
consistency, and funds-impacting regressions. Testing/coverage is
intentionally reduced to a placeholder in Core, so validation relies on
Mobile’s test suite.
> 
> **Overview**
> Replaces the stub `PerpsController` with the full synced
implementation, expanding controller state/metadata and exposing a broad
messenger API for perps operations (orders, positions, funding,
eligibility, deposits/withdrawals, provider/network switching, and
live-data subscriptions).
> 
> Adds multi-provider support (HyperLiquid default, MYX behind a feature
flag, and an `AggregatedPerpsProvider` mode), plus background
market/user-data preloading and stream-pausing helpers to reduce UI
races during trading operations.
> 
> Updates packaging for publishing: adds a sync provenance file, expands
runtime/dev dependencies for provider + cross-controller integrations,
adjusts Jest coverage to only include `tests/placeholder.test.ts`, and
removes the prior controller unit test while updating the changelog to
document the full initial release contents.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2fbf70d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Nick Gambino <35090461+gambinish@users.noreply.github.com>
Co-authored-by: Nicholas Gambino <nicholas.gambino@consensys.net>
Co-authored-by: Nick Gambino <ngambino0192@gmail.com>
Co-authored-by: Elliot Winkler <elliot.winkler@gmail.com>